<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.5.2" />
<title>Gerrit Code Review - Mail Templates</title>
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #dddddd;
  color: #777777;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > div.content {
  white-space: pre;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}


@media print {
  div#footer-badges { display: none; }
}

div#toc {
  margin-bottom: 2.5em;
}

div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock-content {
  white-space: pre;
}
div.verseblock-attribution {
  padding-top: 0.75em;
  text-align: left;
}

div.exampleblock-content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      // Use [\s\S] in place of . so multi-line matches work.
      // Because JavaScript has no s (dotall) regex flag.
      note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      spans[i].innerHTML =
        "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
        "' title='View footnote' class='footnote'>" + n + "</a>]";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
}

}
/*]]>*/
</script>
</head>
<body>
<div id="header">
<h1>Gerrit Code Review - Mail Templates</h1>
<span id="revnumber">version 2.3</span>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>Gerrit uses velocity templates for the bulk of the standard mails it sends out.
There are builtin default templates which are used if they are not overridden.
These defaults are also provided as examples so that administrators may copy
them and easily modify them to tweak their contents.</p></div>
</div>
</div>
<h2 id="_template_locations_and_extensions">Template Locations and Extensions:</h2>
<div class="sectionbody">
<div class="paragraph"><p>The default example templates reside under:  <tt>'$site_path'/etc/mail</tt> and are
terminated with the double extension <tt>.vm.example</tt>. Modifying these example
files will have no effect on the behavior of Gerrit.  However, copying an
example template to an equivalently named file without the <tt>.example</tt> extension
and modifying it will allow an administrator to customize the template.</p></div>
</div>
<h2 id="_supported_mail_templates">Supported Mail Templates:</h2>
<div class="sectionbody">
<div class="paragraph"><p>Each mail that Gerrit sends out is controlled by at least one template, these
are listed below.  Change emails are influenced by two additional templates,
one to set the subject line, and one to set the footer which gets appended to
all the change emails (see <tt>ChangeSubject.vm</tt> and <tt>ChangeFooter.vm</tt> below.)</p></div>
<h3 id="_abandoned_vm">Abandoned.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>Abandoned.vm</tt> template will determine the contents of the email related
to a change being abandoned.  It is a <tt>ChangeEmail</tt>: see <tt>ChangeSubject.vm</tt> and
<tt>ChangeFooter.vm</tt>.</p></div>
<h3 id="_changefooter_vm">ChangeFooter.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>ChangeFooter.vm</tt> template will determine the contents of the footer
text that will be appended to emails related to changes (all <tt>ChangeEmails)</tt>.</p></div>
<h3 id="_changesubject_vm">ChangeSubject.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>ChangeSubject.vm</tt> template will determine the contents of the email
subject line for ALL emails related to changes.</p></div>
<h3 id="_comment_vm">Comment.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>Comment.vm</tt> template will determine the contents of the email related to
a user submitting comments on changes.  It is a <tt>ChangeEmail</tt>: see</p></div>
<h3 id="_merged_vm">Merged.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>Merged.vm</tt> template will determine the contents of the email related to
a change successfully merged to the head.  It is a <tt>ChangeEmail</tt>: see
<tt>ChangeSubject.vm</tt> and <tt>ChangeFooter.vm</tt>.</p></div>
<h3 id="_mergefail_vm">MergeFail.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>MergeFail.vm</tt> template will determine the contents of the email related
to a failure upon attempting to merge a change to the head.  It is a</p></div>
<h3 id="_newchange_vm">NewChange.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>NewChange.vm</tt> template will determine the contents of the email related
to a user submitting a new change for review. It is a <tt>ChangeEmail</tt>: see
<tt>ChangeSubject.vm</tt> and <tt>ChangeFooter.vm</tt>.</p></div>
<h3 id="_registernewemail_vm">RegisterNewEmail.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>RegisterNewEmail.vm</tt> template will determine the contents of the email
related to registering new email accounts.</p></div>
<h3 id="_replacepatchset_vm">ReplacePatchSet.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>ReplacePatchSet.vm</tt> template will determine the contents of the email
related to a user submitting a new patchset for a change.  It is a
<tt>ChangeEmail</tt>: see <tt>ChangeSubject.vm</tt> and <tt>ChangeFooter.vm</tt>.</p></div>
<h3 id="_restored_vm">Restored.vm</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>Restored.vm</tt> template will determine the contents of the email related
to a change being restored.  It is a <tt>ChangeEmail</tt>: see <tt>ChangeSubject.vm</tt> and
<tt>ChangeFooter.vm</tt>.</p></div>
</div>
<h2 id="_mail_variables_and_methods">Mail Variables and Methods</h2>
<div class="sectionbody">
<div class="paragraph"><p>Mail templates can access and display objects currently made available to them
via the velocity context.  While the base objects are documented here, it is
possible to call public methods on these objects from templates.  Those methods
are not documented here since they could change with every release.  As these
templates are meant to be modified only by a qualified sysadmin, it is accepted
that writing templates for Gerrit emails is likely to require some basic
knowledge of the class structure to be useful.  Browsing the source code might
be necessary for anything more than a minor formatting change.</p></div>
<h3 id="_warning">Warning</h3><div style="clear:left"></div>
<div class="paragraph"><p>Be aware that modifying templates can cause them to fail to parse and therefor
not send out the actual email, or worse, calling methods on the available
objects could have internal side effects which would adversely affect the
health of your Gerrit server and/or data.</p></div>
<h3 id="_all_outgoingemails">All OutgoingEmails</h3><div style="clear:left"></div>
<div class="paragraph"><p>All outgoing emails have the following variables available to them:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
$email
</dt>
<dd>
<div class="paragraph"><p>A reference to the class constructing the current <tt>OutgoingEmail</tt>.  With this
reference it is possible to call any public method on the OutgoingEmail class
or the current child class inherited from it.</p></div>
</dd>
<dt class="hdlist1">
$messageClass
</dt>
<dd>
<div class="paragraph"><p>A String containing the messageClass</p></div>
</dd>
<dt class="hdlist1">
$StringUtils
</dt>
<dd>
<div class="paragraph"><p>A reference to the Apache <tt>StringUtils</tt> class.  This can be very useful for
formatting strings.</p></div>
</dd>
</dl></div>
<h3 id="_change_emails">Change Emails</h3><div style="clear:left"></div>
<div class="paragraph"><p>All change related emails have the following additional variables available to them:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
$change
</dt>
<dd>
<div class="paragraph"><p>A reference to the current <tt>Change</tt> object</p></div>
</dd>
<dt class="hdlist1">
$changeId
</dt>
<dd>
<div class="paragraph"><p>Id of the current change (a <tt>Change.Key</tt>)</p></div>
</dd>
<dt class="hdlist1">
$coverLetter
</dt>
<dd>
<div class="paragraph"><p>The text of the <tt>ChangeMessage</tt></p></div>
</dd>
<dt class="hdlist1">
$branch
</dt>
<dd>
<div class="paragraph"><p>A reference to the branch of this change (a <tt>Branch.NameKey</tt>)</p></div>
</dd>
<dt class="hdlist1">
$fromName
</dt>
<dd>
<div class="paragraph"><p>The name of the from user</p></div>
</dd>
<dt class="hdlist1">
$projectName
</dt>
<dd>
<div class="paragraph"><p>The name of this change&#8217;s project</p></div>
</dd>
<dt class="hdlist1">
$patchSet
</dt>
<dd>
<div class="paragraph"><p>A reference to the current <tt>PatchSet</tt></p></div>
</dd>
<dt class="hdlist1">
$patchSetInfo
</dt>
<dd>
<div class="paragraph"><p>A reference to the current <tt>PatchSetInfo</tt></p></div>
</dd>
</dl></div>
</div>
<h2 id="_see_also">See Also</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
<a href="http://velocity.apache.org/">velocity</a>
</p>
</li>
</ul></div>
</div>
<hr style="
  height: 2px;
  color: silver;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
">
<div class="paragraph"><p>Part of <a href="index.html">Gerrit Code Review</a></p></div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Version 2.3<br />
Last updated 2012-03-05 18:44:59 MDT
</div>
</div>
</body>
</html>
